ayFX replayer using asMSX syntax

code: SapphiRe
source: http://z80st-software.blogspot.com/

many thanks to AR for testing  v1.0 and for suggestions about explicit  priority
and relative volume

thanks  to  k0ga  for  their  suggestions  about  using  ayFX  multisound  banks
instead of single ayFX samples


Version History
---------------
12-02-2009 v1.2   The replayer uses ayFX multisound banks instead of ayFX samples.
22-01-2009 v1.11  Some routines relocated to compact the code.
                  When ayFX volume is zero, ayFX values are not copied in to AYREGS.
19-01-2009 v1.1f  All samples are played allways at maximum volume.
           v1.1r  The priority controls also the relative volume of the sample.
17-01-2009 v1.1   Explicit priority (as suggested by AR). Internal release only.
15-01-2009 v1.0f  Bugfix release (corrected a bug when using noise channel).
09-06-2008 v1.0   Initial release.


What is?
--------
This replayer allows to  use ayFX samples on  your MSX games. Also  it interacts
with your  favourite music  replayer (for  instance PT3)  and overwrites the PSG
registers output generated by the music  replayer, so you can write the  correct
values to PSG registers for music and FX at the same time.

This replayer uses a switching channel  routine that mixes the ayFX sample  in a
different PSG channel each frame. This way the music played is less affected  by
the FX samples. When the sample volume  is zero no ayFX values are copied  in to
PSG registers.

Also each sample can be played with a different priority (from 0 to 15).  Higher
values result in less priority. The playing of a sample can be interrupted if  a
new sample with higher priority is tried to be played.

There are two different versions of the replayer:

-Fixed volume version: all  samples are played at  their own volume (defined  on
the samples)
-Relative volume  version: the  priority also  sets the  relative volume  of the
sample


How can I write ayFX samples?
-----------------------------
You can use the ayFX editor made by shiru for Windows. Download it from:

                          http://shiru.untergrund.net

Since version 1.2, you  must save the samples  as a bank, using  the "Save bank"
or "Save bank w/o names" options to save a multisound bank. The only  difference
between these two options  is that "Save bank"  will also save the  names of the
samples.

A bank can contain up to 256 ayFX samples.


How to use (both fixed and relative volume versions)
----------------------------------------------------

There are three main  routines on this player:  setup a bank, init  a sample and
play a frame of a sample.

-Bank setup:

First  of all,  you need  to call  the ayFX_SETUP  procedure to  initialize  the
correct values of  the replayer. When  calling ayFX_SETUP you must set on hl the
address of the sound bank you want to use.

-Init a sample:

When you want to play an ayFX sample,  you need to put on register A (from  0 to
255) the index of the sample in the bank, and  in register C the priority of the
sample, and  call to  ayFX_INIT procedure.  Legal sample  priorities are  from 0
(highest  priority)  to 15  (lowest  priority). Higher  values  may cause  wrong
results.

The ayFX_INIT procedure returns a value on register A for debugging purposes:

0: no errors, the new sample has been correctly initialized
1: priority error, there's a sample with higher priority being played
2: index error, the current bank don't have a sample with such index

-Play a frame of a sample:

To play a  frame of the  stream, just call  to ayFX_PLAY after  a music replayer
changed the ram copy of PSG registers (located under AYREGS label). If the  ayFX
frame produces no sound output, the aproppriate registers will remain unchanged.

The suggested calling sequence is:

HALT (vblank sinchronization)
...
call PT3_ROUT (or a similar routine that copy AYREGS ram zone on PSG registers)
...
call PT3_PLAY (or a similar routine that play a frame of the main music)
...
call ayFX_PLAY
...


Additional comments about relative volume version
-------------------------------------------------
When using the relative volume  version, the replayer uses priority  as relative
volume. So 0 (highest priority)  results on relative volume 15  (highest volume)
and 15 (lowest priority) results on relative volume 0 (silence). This comes from
an idea of AR, which can be resumed in the following sentence:

                        "Closer FX have to sound louder,
             and they must have a higher priority than far sounds"

As the PSG volumes are not linear, the replayer uses the same volume table  that
PT3 replayer. So, if you use this ayFX replayer with the PT3 one, you don't need
to explicitly put the table on your code, because the ayFX replayer looks for it
on the same label (VT_) than PT3 replayer.

If you're not using PT3 replayer, just uncomment the VT_ label at the end of the
ayFX-ROM.asm file, and the volume table will be automatically loaded from vt.bin
file.


Contact
-------
For any comments, bugs or suggestions, send an email to

                            z80st.software@gmail.com
